home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / perl5 / Text::ParseWords.z / Text::ParseWords
Encoding:
Text File  |  2002-10-03  |  4.9 KB  |  133 lines
  1.  
  2.  
  3.  
  4. TTTTeeeexxxxtttt::::::::PPPPaaaarrrrsssseeeeWWWWoooorrrrddddssss((((3333))))                                        TTTTeeeexxxxtttt::::::::PPPPaaaarrrrsssseeeeWWWWoooorrrrddddssss((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Text::ParseWords - parse text into an array of tokens or array of arrays
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.        use Text::ParseWords;
  13.        @lists = &nested_quotewords($delim, $keep, @lines);
  14.        @words = "ewords($delim, $keep, @lines);
  15.        @words = &shellwords(@lines);
  16.        @words = &parse_line($delim, $keep, $line);
  17.        @words = &old_shellwords(@lines); # DEPRECATED!
  18.  
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      The &_n_e_s_t_e_d__q_u_o_t_e_w_o_r_d_s() and &_q_u_o_t_e_w_o_r_d_s() functions accept a delimiter
  22.      (which can be a regular expression) and a list of lines and then breaks
  23.      those lines up into a list of words ignoring delimiters that appear
  24.      inside quotes.  &_q_u_o_t_e_w_o_r_d_s() returns all of the tokens in a single long
  25.      list, while &_n_e_s_t_e_d__q_u_o_t_e_w_o_r_d_s() returns a list of token lists
  26.      corresponding to the elements of @lines.  &_p_a_r_s_e__l_i_n_e() does tokenizing
  27.      on a single string.  The &*_q_u_o_t_e_w_o_r_d_s() functions simply call
  28.      &_p_a_r_s_e__l_i_n_e_s(), so if you're only splitting one line you can call
  29.      &_p_a_r_s_e__l_i_n_e_s() directly and save a function call.
  30.  
  31.      The $keep argument is a boolean flag.  If true, then the tokens are split
  32.      on the specified delimiter, but all other characters (quotes,
  33.      backslashes, etc.) are kept in the tokens.  If $keep is false then the
  34.      &*_q_u_o_t_e_w_o_r_d_s() functions remove all quotes and backslashes that are not
  35.      themselves backslash-escaped or inside of single quotes (i.e.,
  36.      &_q_u_o_t_e_w_o_r_d_s() tries to interpret these characters just like the Bourne
  37.      shell).  NB: these semantics are significantly different from the
  38.      original version of this module shipped with Perl 5.000 through 5.004.
  39.      As an additional feature, $keep may be the keyword "delimiters" which
  40.      causes the functions to preserve the delimiters in each string as tokens
  41.      in the token lists, in addition to preserving quote and backslash
  42.      characters.
  43.  
  44.      &_s_h_e_l_l_w_o_r_d_s() is written as a special case of &_q_u_o_t_e_w_o_r_d_s(), and it does
  45.      token parsing with whitespace as a delimiter-- similar to most Unix
  46.      shells.
  47.  
  48. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  49.      The sample program:
  50.  
  51.        use Text::ParseWords;
  52.        @words = "ewords('\s+', 0, q{this   is "a test" of\ quotewords \"for you});
  53.        $i = 0;
  54.        foreach (@words) {
  55.            print "$i: <$_>\n";
  56.            $i++;
  57.        }
  58.  
  59.      produces:
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTeeeexxxxtttt::::::::PPPPaaaarrrrsssseeeeWWWWoooorrrrddddssss((((3333))))                                        TTTTeeeexxxxtttt::::::::PPPPaaaarrrrsssseeeeWWWWoooorrrrddddssss((((3333))))
  71.  
  72.  
  73.  
  74.        0: <this>
  75.        1: <is>
  76.        2: <a test>
  77.        3: <of quotewords>
  78.        4: <"for>
  79.        5: <you>
  80.  
  81.      demonstrating:
  82.  
  83.      0 a simple word
  84.  
  85.      1 multiple spaces are skipped because of our $delim
  86.  
  87.      2 use of quotes to include a space in a word
  88.  
  89.      3 use of a backslash to include a space in a word
  90.  
  91.      4 use of a backslash to remove the special meaning of a double-quote
  92.  
  93. quote)
  94.      5 another simple word (note the lack of effect of the backslashed double-
  95.  
  96.      Replacing "ewords('\s+', 0, q{this   is...}) with &shellwords(q{this
  97.      is...}) is a simpler way to accomplish the same thing.
  98.  
  99. AAAAUUUUTTTTHHHHOOOORRRRSSSS
  100.      Maintainer is Hal Pomeranz <pomeranz@netcom.com>, 1994-1997 (Original
  101.      author unknown).  Much of the code for &_p_a_r_s_e__l_i_n_e() (including the
  102.      primary regexp) from Joerk Behrends <jbehrends@multimediaproduzenten.de>.
  103.  
  104.      Examples section another documentation provided by John Heidemann
  105.      <johnh@ISI.EDU>
  106.  
  107.      Bug reports, patches, and nagging provided by lots of folks-- thanks
  108.      everybody!  Special thanks to Michael Schwern <schwern@envirolink.org>
  109.      for assuring me that a &_n_e_s_t_e_d__q_u_o_t_e_w_o_r_d_s() would be useful, and to Jeff
  110.      Friedl <jfriedl@yahoo-inc.com> for telling me not to worry about error-
  111.      checking (sort of-- you had to be there).
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.